home *** CD-ROM | disk | FTP | other *** search
/ SPACE 1 / SPACE - Library 1 - Volume 1.iso / apps / 630 / gemgs.doc next >
Text File  |  1992-09-05  |  17KB  |  410 lines
  1.  
  2. Documentation for gemGS 1.2.             7/31/92
  3.  
  4. GemGS may be freely copied and distributed, although the source is
  5. copyrighted.  Portions of the source were taken from the Unix
  6. Ghostview distribution, and Tim Theisen holds the copyright to those
  7. parts.  If you modify the source, please change the name of the
  8. program so that there is no confusion.
  9.  
  10.  
  11. INTRODUCTION:
  12.  
  13. GemGS is a GEM shell for Ghostscript on Atari ST/TT computers.  It is
  14. far too large, and has far too many features, since I used it as an
  15. exercise to learn some aspects of GEM programming.  It is, however,
  16. fun to play with, and may be useful to those who hate command line
  17. interpreters.  The only real advantage that the shell offers over the
  18. command line interface is the ability to choose specific pages from
  19. large documents for GS to display.  Unfortunately the speed (slow) of
  20. the page selection code nearly negates any benefit (hey, I didn't
  21. write that part of the code).
  22.  
  23. In essence, gemGS simply sets up a GS environment, allows the user to
  24. pick Ghostscript options with the mouse, and then executes GS.
  25.  
  26. Some frills are:
  27.  
  28. 1) Setup file that allows the user to define menu items, select
  29.    default options, and define environment variables.
  30.  
  31. 2) A user definable "tool" menu, which can be loaded with all kinds
  32.    of gem, tos, and ttp utility programs, which can then be run from
  33.    the shell in a semi-integrated fashion.
  34.  
  35. 3) GemGS can be installed so that it automatically displays PostScript
  36.    files which have been double-clicked.
  37.  
  38. Disadvantages are:
  39.  
  40. 1) It is tedious to use if you like CLIs.
  41.  
  42. 2) Postscript document scanning for page selection is sloooow.  I
  43.    stole most of the code for this from the Ghostview (X Windows shell
  44.    for GS) distribution, so I will pass the blame until I get time
  45.    to look into speeding it up.
  46.  
  47. 3) The menu bar and the command line dialog are too large for low
  48.    resolution on the ST. You can sort of use gemGS, but not too well.
  49.    I may fix up a low res version sometime in the future.
  50.  
  51. BASIC USAGE:
  52.  
  53. From a command line: gemgs [infile1 infile2 ...]
  54.  
  55. GemGS initializes the background and mouse itself, so it should work
  56. properly when run from a shell ....  except, for some reason I have
  57. not yet discovered, it is sometimes necessary to type 'mson' before
  58. running gemGS from gulam. GemGS does not restore the cursor when it
  59. exits (that would mess up desktop users), so if you run from a shell,
  60. you may end up without a visible cursor in the end unless you execute
  61. gem programs from within some kind of wrapper.
  62.  
  63. Once inside the gemGS, you:
  64.  
  65. 1) pick the input and output files from the File menu,
  66. 2) choose the device from the Device menu,
  67. 3) pick the resolution from the Resolution menu,
  68. 4) pick any options from the options menu,
  69. 5) click Run under the File menu.
  70.  
  71. Everything in items 1-4, except for choosing the input file, can be
  72. done from the startup file.  The input file can be entered on the
  73. command line.  If you do both of these, all you need to do from inside
  74. the shell is 5.
  75.  
  76. Depending on how the options are set, selecting the Run menu item will
  77. either start GS running, or you will get an editable dialog showing the
  78. command line that will be passed to GS and asking for confirmation.
  79. After this, you interact with GS as usual; see the GS documentation.
  80. When GS exits, you will return to the shell.
  81.  
  82. GemGS can also be installed on the desktop to automatically display
  83. PostScript files which have been double-clicked. To do this, use
  84. whatever procedure is necessary on your machine to install gemGS
  85. as the default application for files with extension .ps. Then make
  86. sure the line "autorun 1" is in the the gemgs.rc startup file. When
  87. gemGS has been given command line parameters, autorun tells it
  88. to execute GS immediately on the input files, disregarding the
  89. state of the "confirm" option. If there are no input files, gemGS
  90. enters interactive mode as usual.
  91.  
  92. NOTE: GemGS looks searches the PATH environment variable for the
  93. file 'gs.ttp'. If PATH is not set, or you changed the name of
  94. the ghostscript executable, you will get a dialog stating that
  95. GS could not be run.
  96.  
  97. The screen driver for GS has been modified to include support for
  98. windows.  This modification was intended for use with gemGS, but can
  99. be used with GS alone.  GS figures out how to handle the windows by
  100. looking at the environment variable GS_WIN.  If GS_WIN is not set, the
  101. GS screen driver uses no windows.  If GS_WIN=interact (lower case),
  102. then images are displayed in a window, but text mode is entered after
  103. every page.  This allows interactive entry of commands at the GS
  104. command line.  "Interact" mode is intended to be used when GS is run
  105. from a shell.  If GS_WIN=batch, the screen driver assumes that you are
  106. running GS in such a fashion that no real interaction with GS takes
  107. place, i.e., GS prints no messages to you, and you type no commands to
  108. it.  This is the mode that gemGS uses when the "windows" option is
  109. selected.  This hides the fact that GS is really a command-line driven
  110. program, but it is not flawless.  For example, if an error occurs in
  111. GS when GS_WIN=batch, the error message will be written all over the
  112. screen background, menus, etc.  As long as nothing abnormal happens,
  113. it works OK.  See the Atari-specific GS documentation for instructions
  114. on screen driver use. Of course, if you have an old version of GS,
  115. the GS_WIN variable will be ignored.
  116.  
  117. In GS 2.41 Atari revision 1, the screen driver redraws the screen
  118. background when windows are enabled. Unfortunately, on color systems,
  119. it uses the wrong color. This will be fixed in GS > 2.5.
  120.  
  121. MENUS:
  122.  
  123. Some menu items have alternate key bindings. Those that do, have the
  124. binding shown beside the menu entry.
  125.  
  126. #--------------------------------------------------------------------
  127.  
  128. Desk:
  129.  
  130. About gemGS - Displays a dialog about gemGS. For those serious-minded
  131.     folks who are uncertain, this dialog is a simultaneous
  132.     commentary on the current job situation for theoretical
  133.     physicists and the complaints of shareware authors who
  134.     feel that users never pay the requested fee. In short
  135.     it is a joke. Do you think anyone will pay up?
  136.  
  137. #--------------------------------------------------------------------
  138.  
  139. File:
  140.  
  141. Run   - Run Ghostscript with the current command parameters. If the
  142. ALT-r    "confirm" option is chosen, a dialog will display with the
  143.     GS command line.
  144.  
  145. Input - Presents a file selector so that the input file can be chosen.
  146. ALT-i    Note that only one file can be entered in this fashion.
  147.     Multiple input files have to be entered from a command line
  148.     or typed in the editable field which is displayed when the
  149.     "confirm" option is set.
  150.  
  151. Output- Presents a dialog for selecting output to PRN: (the centronics)
  152. ALT-o    port), CEN: (like PRN: only faster--only works on regular STs,
  153.     i.e. not STes or TTs), or to a file. If a file is desired, a
  154.     file selector is presented.
  155.  
  156. Quit  - Self explanatory, I hope.
  157. ALT-q
  158.  
  159. #--------------------------------------------------------------------
  160.  
  161. Device:
  162.  
  163. This menu item contains 2 standard entries and up to 8 more user-defined
  164. entries. The 2 standard entries are described here.
  165.  
  166. stvdi - Selects the screen device as the GS output device.
  167.     GemGS assumes that the screen device is the default device.
  168.     Other devices can be loaded into this menu, and the default
  169.     device can be selected in the startup file. More on this later.
  170.  
  171. Other - Presents a dialog for you to type in a device which has not
  172.     been loaded into the menu.
  173.  
  174. #--------------------------------------------------------------------
  175.  
  176. Resolution:
  177.  
  178. This menu item contains 2 standard entries and up to 8 more user-defined
  179. entries. The 2 standard entries are described here.
  180.  
  181. Default - Use the default resolution of the selected device.
  182.  
  183. Other   - Presents a dialog for you to type in a resolution which has
  184.       not been loaded into the menu. It is up to the user to use
  185.       resolutions that the chosen device can handle.
  186.  
  187. #--------------------------------------------------------------------
  188.  
  189. Options:
  190.  
  191. All of the following options can be set from the gemGS startup file.
  192.  
  193. Confirm - Display a dialog containing the GS command line and ask
  194.     for confirmation before running GS. The command line can
  195.     be edited at this time.
  196.  
  197. Quiet - Run GS in quiet mode, no startup/informative messages.
  198.  
  199. NoPause - Tells GS not to pause and the end of every page in a
  200.     multi-page document. If NoPause is turned off, you have
  201.     to hit RETURN at the end of every page.
  202.  
  203. AutoQuit - GS will quit when it runs out of input. By default, GS
  204.     enters interactive mode when it reaches the end of its
  205.     input files.
  206.  
  207. Windows - This tells GS to display the image in a window. It is
  208.     only enabled when the screen device is selected. It is
  209.     ignored for printer devices. When this option is selected,
  210.     the environment variable GS_WIN is defined with the value
  211.     "batch". Selecting "windows" will automatically select
  212.     the "quiet", "nopause", and "autoquit" options. This is
  213.     so that output from GS does not get written all over the
  214.     GEM screen. Unfortunately, however, any GS error messages
  215.     will be ugly. Note that old versions of GS (generally < 2.5,
  216.     although some versions of 2.41 are OK) cannot display in
  217.     windows, and will ignore the GS_WIN envorinment variable.
  218.  
  219. Geometry - Display a dialog that allows a geometry to be chosen.
  220.     The Geometry is just the size of the image in pixels,
  221.     like 640x400. Every device has a default geometry, but
  222.     you can change it if you like.
  223.  
  224. Clist - Print images in bands for machines with limited memory.
  225.     GS can print imaging commands to a "Command list" and
  226.     then read these commands back repeatedly to construct large
  227.     images in bands. This is MANDATORY on 1M machines. When "Clist"
  228.     is selected, a dialog is presented to allow the user to
  229.     enter the size of the buffer (in bytes) that will be used
  230.     to hold the bands. Entering 100000 means that the image will
  231.     be printed in chunks of 100K bytes each. You will need to
  232.     have 100K of free memory AFTER GS is loaded and has allocated
  233.     memory for needs other than the print buffer.
  234.  
  235. Pages - If no input file is selected, a file selector is presented.
  236.     The input file is then scanned to determine the number of
  237.     pages and their order, etc. This can take a very long time
  238.     for long documents (about 5 minutes for 30 pages). A dialog
  239.     is then presented so that the desired pages can be selected.
  240.     Pages are selected by EITHER clicking on the appropriate
  241.     boxes OR typing a string in the editable text field provided.
  242.     The contents of the editable field override the buttons. The
  243.     buttons are used only if the field is empty. The Clear button
  244.     in this dialog clears all button selections AND the editable
  245.     field. Use the arrows to scroll up and down if there are
  246.     more than 10 pages. The selected pages are written to a
  247.     file called "pspage.ps", and that file is automatically
  248.     passed to GS instead of the original input file. "Pspage.ps"
  249.     is deleted when gemgs exits, but is available for viewing
  250.     and editing from within gemGS (by using programs in the tool
  251.     menu).
  252.  
  253. #--------------------------------------------------------------------
  254.  
  255. Tools:
  256.  
  257. This menu contains no default entries.  Everything in this menu is
  258. loaded from the gemGS startup file.  This menu is very flexible, and
  259. is intended to provide a convenient interface to programs which are
  260. often used on conjunction with GS.  For example, one menu entry in the
  261. example startup file runs the micro-emacs editor on the input file.
  262. Another entry runs dvips, a program that converts TeX dvi files to
  263. postscript format.  A help entry runs micro-emacs on this
  264. documentation file.  The programs can be of GEM, TOS, or TTP type.
  265.  
  266. In the definition of a tool menu entry, there are a few keywords that
  267. allow a limited use of dialogs and file selectors with programs in the
  268. tools menu.  See the documentation on the startup file for more
  269. details.
  270.  
  271.  
  272. STARTUP FILE:
  273.  
  274. On startup, gemGS looks for a file named "gemgs.rc".  If this file
  275. cannot be found in the current directory, then the directory contained
  276. in the environment variable HOME is searched.  An alert warns if no
  277. startup file can be found.  The syntax of the allowed commands is
  278. documented in the example startup file which should be included in
  279. this distribution.  A copy is included here for convenience.
  280.  
  281. #--------------------------------------------------------------------
  282. #    Begin example gemgs.rc
  283. #--------------------------------------------------------------------
  284.  
  285. #
  286. # Example setup file for gemGS.
  287. #
  288. # The format for the setup commands is currently very strict, so
  289. # pay close attention to the precise form. Never use more than
  290. # a single space, and don't use any tabs.
  291. #
  292. # Any line which cannot be recognized is ignored, but I have
  293. # conventionally used a '#' to denote a comment.
  294. #
  295.  
  296. # Set default device. This overrides the GS_DEVICE environment
  297. # variable. If this is missing, the default is the stvdi device.
  298. # The device name must match name that GS knows for the device.
  299. # To see what devices are installed, type gs -?.
  300. # Format is "device gs_device_name".
  301.  
  302. device stvdi
  303.  
  304. # Set gemGS to autorun. When autorun is set to 1, gemGS will immediately
  305. # run GS on the input file, ignoring the 'confirm' option if it is set.
  306. # If there is no input file, the autorun variable is ignored and gemGS
  307. # runs interactively. This allows PostScript files to be immediately
  308. # displayed with gemGS by simply double-clicking on the file. Of course,
  309. # you must install gemGS as an desktop application first.
  310.  
  311. autorun 1
  312.  
  313. # Set the default options.
  314. # Format for on/off options is "option_name 1/0".
  315.  
  316. #confirm 1
  317. #quiet 0
  318. nopause 0
  319. #autoquit 1
  320. windows 1
  321.  
  322. # Format for other options is "option_name option_string".
  323.  
  324. #resolution 60
  325. #geometry 400x400
  326. #clist 150000
  327.  
  328. # Set environment variables. PATH is used in searching for GS
  329. # and for tools. GS_DEVICE is the default device if the "device"
  330. # command appears nowhere in this file. GS_LIB is the path that
  331. # GS searches for ps files, fonts, etc.
  332.  
  333. setenv PATH=c:\bin,f:\gs
  334. #setenv GS_DEVICE=deskjet
  335. setenv GS_LIB=f:\gs,f:\gs\ps,f:\gs\fonts
  336.  
  337. # Add devices to the device menu. The device name must match the
  338. # Ghostscript name for the device. Type 'gs -h' to see which
  339. # devices are available in the GS executable that you have.
  340. # Format is "devmenu gs_device_name".
  341.  
  342. devmenu deskjet
  343. devmenu epson
  344. devmenu paintjet
  345.  
  346. # Add resolutions to the resolution menu. The default screen
  347. # resolution is 80dpi. All resolution entries are in dots-per-inch.
  348. # The resolution string should be whatever comes after the GS
  349. # -r command line switch. It is up to you to specify a resolution
  350. # that the given device can handle.
  351. # Format is "resmenu resolution_string".
  352.  
  353. resmenu 60
  354. resmenu 100
  355. resmenu 120x60
  356.  
  357. # Add tools to the tool menu. These can be GEM, TOS, or TTP programs.
  358. # PATH will be searched for any program specified. If the program
  359. # is not in the specified PATH environment variable, the full program
  360. # name must be given. The following special keywords are recognized
  361. # by gemGS as command line options for tool menu entries:
  362. #
  363. # infile:    substitute the input file in the position of this keyword,
  364. # outfile:    substitute the output file in the position of this keyword,
  365. # fsel:        present a file selector, put the selection in this position,
  366. # dialog:    present a dialog with an editable text string, input here,
  367. # pause:    pause after tool terminates before redrawing screen,
  368. # gem:        specifies that program is a GEM program so that screen
  369. #            and mouse are handled properly.
  370. #
  371. # Format is "toolmenu menu_string program_name [command line options]"
  372.  
  373. toolmenu gemGS-Help ue gemgs.doc
  374. toolmenu GS-Help ue f:\gs\doc\use.doc
  375. toolmenu Edit-File ue dialog
  376. toolmenu Edit-Input ue infile
  377. toolmenu Print-Output bpr outfile
  378. toolmenu TeXdvi-to-PS dvips fsel
  379. toolmenu Dega-to-PS psst gem
  380. toolmenu Shell gulam
  381. toolmenu Directory ls -l pause
  382. toolmenu DiskSpace df c: d: e: f: g: h: pause
  383.  
  384. #--------------------------------------------------------------------
  385. #    End example gemgs.rc
  386. #--------------------------------------------------------------------
  387.  
  388.  
  389. ACKNOWLEDGEMENTS:
  390.  
  391. The code for scanning PostScript documents and printing selected
  392. pages to a file was taken from the source for Ghostview, by
  393. Tim Theisen.
  394.  
  395.  
  396. SUGGESTIONS, QUESTIONS, and BUG REPORTS:
  397.  
  398. Any suggestions for improving gemGS are welcome.
  399. Questions and bug reports can be sent to:
  400.  
  401. Tim Gallivan
  402. Center for Relativity
  403. Department of Physics
  404. University of Texas at Austin
  405. Austin, TX 78712
  406.  
  407. timg@landau.ph.utexas.edu
  408.  
  409. /* EOF */
  410.